klona

What is klona?

The klona npm package is a JavaScript utility for deep cloning objects. It allows developers to create a deep copy of an object, ensuring that changes to the new object do not affect the original object. This is particularly useful when working with complex data structures or when you need to ensure data immutability.

What are klona's main functionalities?

Deep cloning of objects

This feature allows you to create a deep clone of an object, which means that nested objects are also cloned, and changes to the cloned object do not affect the original object.

{"const klona = require('klona');\nconst original = { a: 1, b: { c: 2 } };\nconst copy = klona(original);\ncopy.b.c = 3;\nconsole.log(original.b.c); // 2\nconsole.log(copy.b.c); // 3"}

Deep cloning of arrays

Similar to object cloning, klona can also deep clone arrays, including nested arrays, ensuring that modifications to the cloned array do not affect the original array.

{"const klona = require('klona');\nconst original = [1, [2, 3], [4, 5]];\nconst copy = klona(original);\ncopy[1][0] = 'changed';\nconsole.log(original[1][0]); // 2\nconsole.log(copy[1][0]); // 'changed'"}

Cloning class instances

klona is capable of cloning instances of classes, allowing you to duplicate an instance and modify the copy without affecting the original instance.

{"const klona = require('klona');\nclass Example {\n  constructor(value) {\n    this.value = value;\n  }\n}\nconst original = new Example(1);\nconst copy = klona(original);\ncopy.value = 2;\nconsole.log(original.value); // 1\nconsole.log(copy.value); // 2"}

Other packages similar to klona

lodash

Lodash is a popular utility library that includes a `cloneDeep` function for deep cloning objects. It is more feature-rich than klona but also larger in size, which might be a consideration for projects where bundle size is a concern.

deep-copy

deep-copy is another npm package that provides deep cloning functionality. It offers similar capabilities to klona but may have different performance characteristics or API nuances.

rfdc

rfdc (Really Fast Deep Clone) is a package that focuses on performance for deep cloning objects and arrays. It claims to be faster than other deep cloning methods, which might make it a preferred choice for performance-critical applications.

README

A tiny (240B to 501B) and fast utility to "deep clone" Objects, Arrays, Dates, RegExps, and more!

Features

• Super tiny and performant
• Deep clone / recursive copies
• Safely handles complex data types
  Array, Date, Map, Object, RegExp, Set, TypedArray, and more

Unlike a "shallow copy" (eg, Object.assign), a "deep clone" recursively traverses a source input and copies its values — instead of references to its values — into a new instance of that input. The result is a structurally equivalent clone that operates independently of the original source and controls its own values.

Why "klona"? It's "clone" in Swedish.
What's with the sheep? Dolly.

Install

$ npm install --save klona

Modes

There are multiple "versions" of klona available, which allows you to bring only the functionality you need!

klona/json

Size (gzip): 240 bytes
Availability: CommonJS, ES Module, UMD
Ability: JSON data types

import { klona } from 'klona/json';

klona/lite

Size (gzip): 354 bytes
Availability: CommonJS, ES Module, UMD
Ability: extends klona/json with support for custom class, Date, and RegExp

import { klona } from 'klona/lite';

klona

Size (gzip): 451 bytes
Availability: CommonJS, ES Module, UMD
Ability: extends klona/lite with support for Map, Set, DataView, ArrayBuffer, TypedArray

import { klona } from 'klona';

klona/full

Size (gzip): 501 bytes
Availability: CommonJS, ES Module, UMD
Ability: extends klona with support for Symbol properties and and non-enumerable properties

import { klona } from 'klona/full';

Usage

import { klona } from 'klona';

const input = {
  foo: 1,
  bar: {
    baz: 2,
    bat: {
      hello: 'world'
    }
  }
};

const output = klona(input);

// exact copy of original
assert.deepStrictEqual(input, output);

// applying deep updates...
output.bar.bat.hola = 'mundo';
output.bar.baz = 99;

// ...doesn't affect source!
console.log(
  JSON.stringify(input, null, 2)
);
// {
//   "foo": 1,
//   "bar": {
//     "baz": 2,
//     "bat": {
//       "hello": "world"
//     }
//   }
// }

API

klona(input)

Returns: typeof input

Returns a deep copy/clone of the input.

Benchmarks

Running Node v12.18.3

The benchmarks can be found in the /bench directory. They are separated into multiple categories:

• JSON – compares an array of objects comprised of JSON data types (String, Number, null, Array, Object)
• LITE – like JSON, but adds RegExp, Date and undefined values
• DEFAULT – object with RegExp, Date, Array, Map, Set, custom class, Int8Array, DataView, Buffer values
• FULL – like DEFAULT, but adds Symbol and non-enumerable properties

Important: Only candidates that pass validation step(s) are listed.
However, lodash and clone are kept to highlight important differences.

Note: The clone/include candidate refers to its includeNonEnumerable option enabled.

Load times:
  lodash/clonedeep   29.257ms
  rfdc                0.511ms
  clone               0.576ms
  clone-deep          2.494ms
  deep-copy           0.451ms
  klona/full          0.408ms
  klona               0.265ms
  klona/lite          0.308ms
  klona/json          0.263ms

Benchmark :: JSON
  JSON.stringify      x   53,899 ops/sec ±0.76% (92 runs sampled)
  lodash              x   46,800 ops/sec ±0.86% (90 runs sampled)
  rfdc                x  221,456 ops/sec ±0.88% (92 runs sampled)
  clone               x   39,537 ops/sec ±0.68% (92 runs sampled)
  clone/include       x   25,488 ops/sec ±1.06% (88 runs sampled)
  clone-deep          x   99,998 ops/sec ±0.91% (93 runs sampled)
  deep-copy           x  141,270 ops/sec ±0.95% (92 runs sampled)
  klona/full          x   55,016 ops/sec ±0.68% (94 runs sampled)
  klona               x  281,215 ops/sec ±0.77% (93 runs sampled)
  klona/lite          x  318,481 ops/sec ±0.72% (91 runs sampled)
  klona/json          x  334,932 ops/sec ±0.66% (93 runs sampled)

Benchmark :: LITE
  lodash              x   36,992 ops/sec ±0.65% (91 runs sampled)
  clone               x   35,974 ops/sec ±1.13% (88 runs sampled)
  clone/include       x   22,609 ops/sec ±1.02% (91 runs sampled)
  clone-deep          x   92,846 ops/sec ±0.66% (93 runs sampled)
  klona/full          x   47,873 ops/sec ±0.83% (88 runs sampled)
  klona               x  226,638 ops/sec ±1.16% (93 runs sampled)
  klona/lite          x  257,900 ops/sec ±0.82% (93 runs sampled)

Benchmark :: DEFAULT
  lodash              x   55,914 ops/sec ±0.75% (93 runs sampled)
    ✘ Buffer
    ✘ Map keys
  clone               x   92,127 ops/sec ±0.83% (94 runs sampled)
    ✘ DataView
  clone/include       x   62,052 ops/sec ±0.88% (93 runs sampled)
    ✘ DataView
  klona/full          x   90,308 ops/sec ±0.68% (89 runs sampled)
  klona               x  230,257 ops/sec ±0.71% (91 runs sampled)

Benchmark :: FULL
  lodash              x   60,361 ops/sec ±0.65% (91 runs sampled)
    ✘ Buffer
    ✘ Map keys
    ✘ Missing non-enumerable Properties
  clone/include       x   47,263 ops/sec ±0.85% (93 runs sampled)
    ✘ DataView
    ✘ Incorrect non-enumerable Properties
  klona/full          x   82,346 ops/sec ±0.62% (93 runs sampled)

Related

• dlv – safely read from deep properties in 120 bytes
• dset – safely write into deep properties in 160 bytes
• dequal – safely check for deep equality in 304 to 489 bytes

License

MIT © Luke Edwards